<html>

<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       https://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->

<body>
Use Java reflection to generate schemas and protocols for existing
classes.

<p>Java types are mapped to Avro schemas as follows:

<ul>

<li><b>Classes</b> are mapped to Avro records. Only concrete classes
  with a no-argument constructor are supported.  All inherited fields
  that are not static or transient are used.  Fields are not permitted
  to be null unless annotated by {@link
  org.apache.avro.reflect.Nullable Nullable} or a {@link
  org.apache.avro.reflect.Union Union} containing {@link java.lang.Void}.</li>

<li><b>Arrays</b> are mapped to Avro array schemas.  If an array's
  elements are a union defined by the {@link
  org.apache.avro.reflect.Union Union} annotation, the "java-element"
  property is set to the union's class, e.g.:
  <pre>{"type": "array", "java-element": "org.acme.Foo"}</pre>
</li>

<li><b>Collection</b> implementations are mapped to Avro array schemas
  with the "java-class" property set to the collection
  implementation, e.g.:
  <pre>{"type": "array", "java-class": "java.util.ArrayList"}</pre>
</li>

<li><b>{@link java.lang.String}</b> is mapped to an Avro string schema.</li>

<li><b>byte[]</b> is mapped to an Avro bytes schema.</li>

<li><b>short</b> is mapped to an Avro int schema with the "java-class"
  property set to "java.lang.Short", e.g.:
  <pre>{"type": "int", "java-class": "java.lang.Short"}</pre>

<li><b>{@link java.math.BigDecimal}, {@link java.math.BigInteger},
  {@link java.net.URI}, {@link java.net.URL}, {@link java.io.File}</b>
  are mapped to an Avro string schema as
  {@link org.apache.avro.reflect.Stringable Stringable} types and
  serialized via their {@link java.lang.Object#toString() toString}
  method and de-serialized via their {@link java.lang.String} constructor.
  This is done via the "java-class", "java-key-class" or
  "java-element-class" depending on whether it is a field, or map key
  or a list/map element, e.g.:
  <pre>{"type": "string", "java-class": "java.math.BigDecimal"}</pre></li>

<li>All other types are mapped as in the {@link org.apache.avro.generic
  generic} API.</li>

</ul>

<p>The {@link org.apache.avro.reflect.Union Union} annotation can be used
to support reflection of schemas for interfaces, abstract base classes
and other uses of polymorphism.

<p>The {@link org.apache.avro.reflect.Stringable Stringable} annotation
will cause a type to be serialized via its {@link java.lang.Object#toString()
toString} method.

<p>Fields annotated with {@link org.apache.avro.reflect.AvroIgnore AvroIgnore} 
will not be written or read to. 

<p> The {@link org.apache.avro.reflect.AvroName AvroName} annotation renames 
the field in the schema to the given name. The reflect datum reader will look 
for a schema field with the given name, when trying to read into such an 
annotated java field. 

<p>The {@link org.apache.avro.reflect.AvroMeta AvroMeta} annotation adds an 
arbitrary key:value pair in the schema at the node of the java field.

<p>The {@link org.apache.avro.reflect.AvroSchema AvroSchema} annotation forces 
the use of an custom schema.

<p>The {@link org.apache.avro.reflect.AvroEncode AvroEncode} annotation forces 
the use of an custom encoder. This annotation overrides 
{@link org.apache.avro.reflect.Stringable Stringable} and 
{@link org.apache.avro.reflect.Nullable Nullable}.


</body>
</html>
